
// 包声明：该注解属于 com.xg.validator.annotations 包
package com.xg.validator.annotation;

// 导入自定义比较操作符枚举
import com.xg.model.enums.CompareOperator;

// Java 标准注解导入
import java.lang.annotation.*;

/**
 * 条件必填字段注解
 *
 * 用于标记某个字段在满足特定条件时必须填写。
 * 条件由依赖字段名（conditionField）、比较操作符（operator）和期望值数组（conditionValues）共同决定。
 */
@Documented
@Retention(RetentionPolicy.RUNTIME) // 注解在运行时依然可用，便于反射读取
@Target(ElementType.FIELD)          // 仅作用于字段
public @interface ConditionalRequired {

    /**
     * 指定触发条件的字段名称
     *
     * 当该字段的值满足给定的操作符与期望值时，当前字段必须非空。
     *
     * @return 条件字段名
     */
    String conditionField();

    /**
     * 指定条件字段应匹配的值列表
     *
     * 只有当 conditionField 的值等于其中某一个值时，当前字段才被要求必填。
     *
     * @return 字符串数组，表示多个可能的条件值
     */
    String[] conditionValues();

    /**
     * 指定条件字段的比较操作符，默认为 EQ（等于）
     *
     * 支持的操作符包括：
     * - EQ: 等于
     * - GT: 大于
     * - LT: 小于
     * - GTE: 大于等于
     * - LTE: 小于等于
     *
     * @return CompareOperator 枚举类型
     */
    CompareOperator operator() default CompareOperator.EQ;

    /**
     * 验证失败时返回的错误提示信息
     *
     * 默认值为 "在特定条件下该字段不能为空"
     *
     * @return 错误提示字符串
     */
    String message() default "在特定条件下该字段不能为空";
}